home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1990: Night of the Living Disc / Night of the Living Disc.2mg / Dev.CD.5 / Utilities / GSBug / GSBug.Specs < prev    next >
Encoding:
Text File  |  1990-06-19  |  11.3 KB  |  278 lines  |  [04] ASCII Text (0x0000)
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                                GSBug Version 1.5
  8.  
  9.  
  10.  
  11. Current Version 1.5B9
  12.  
  13.  
  14. This document details all changes made to the debugger from version 1.3b1,
  15. most of the changes are modifications of older features and bug fixes.
  16.  
  17.  
  18. Bug Fixes:
  19.  
  20. Real Time Tool Breaks - The mechanism for using tool breaks real time has
  21. been modified, the old method never worked quite right, what used to happen
  22. was that when a tool break was to occur, the stub in the dispatch vector
  23. would simply jump into the debugger, this would cause the stack and processor
  24. not to be set as if they came from an interupt, and the next exit of the
  25. debugger would cause code execution to start at an inapropriate case, also
  26. the actual tracing of a tool break would also cause the debugger to
  27. improperly save the current registers, so that the stack/direct page and
  28. processor status might come back damaged from a tool break. The stub has
  29. been modified to now enter the debugger with a break instruction instead
  30. of jumping to the front. This seems to solve all real time tool break
  31. problems.
  32.  
  33. Error tool breaks - These also did not work well, and did not seem to be
  34. used by anyone anyway, so they have been removed to make room for OSBreaks.
  35.  
  36. Version 1.5b3:
  37. % display code was fixed so that the '*' would properly be displayed in
  38.   front of any toolbox glue that is detected.
  39. % Fixed template data display so that if the data being displayed crosses
  40.   a bank boundry, the data is properly followed into the new bank.
  41. % Modified the IN command so that it respects trigger counts of 0 and does
  42.   not insert real time breaks.
  43.  
  44. Version 1.5b5:
  45. % Added Glue tool break support. Now toolbreaks work for regular and glue
  46.   tool breaks. ErrorBreaks do not work for glue as they do not make a lot
  47.   of sense.
  48. % Made debugger work even when a DA window is open. See new features below.
  49. % Added keyClick so that you hear whenever the system draws a key from the
  50.   event queue. Also, cleaned up some comments.
  51.  
  52. Version 1.5b6:
  53. % Added new DebugStr toolcall that can be used to get more from the debugger.
  54.  
  55. Version 1.5b7:
  56. % Added support for real time conditional breaks.
  57. % Added OSBreaks.
  58. % Fixed the Debugger tool calls (like DebugStr ) so that they use the proper
  59.   tool numbers (they had the toolset number in the high byte instead of the
  60.   low byte) Documentation for them should also be right.
  61.  
  62. Version 1.5b8:
  63. % Added a debugger version and status call to the debugger tools.
  64. % Enhanced the OSBreak facility.
  65. % Removed the keyclicks because Dave complained.
  66.  
  67. Version 1.5b9:
  68. % Fixed some bugs.
  69.  
  70.  
  71. New Features:
  72.  
  73. DebugStr:
  74. This feature is designed to allow developers to better know where in their
  75. program the debugger was entered. The way this feature works is that if you
  76. want to enter the debugger programatically you can now also pass a string to
  77. the debugger which will be printed on the bottom line of the screen when the
  78. debugger is entered.
  79.  
  80. The way this mechanism works is a fake tool call that the debugger now
  81. supports. Since this looks like a normal tool call it can be easily called
  82. by any high level language as well as by assembly language.  This toolcall
  83. called DebugStr takes a single parameter, a pointer to a pascal string. When
  84. the tool call is made the debugger is entered as if you had put a break
  85. into your code, but the string you passed is displayed on the screen and
  86. the program counter has been bumped passed the tool call jsl. This way you
  87. can simply resume execution with two simple keystrokes (with the init
  88. version hit 'R' <return>).
  89.  
  90. Calling this new feature might look something like this
  91.  
  92.         PushLong #DebugStr
  93.         ldx #$09FF
  94.         jsl >$E10000
  95.  
  96.     ...
  97. DebugStr    str 'You are about to do blah.'
  98.  
  99. from pascal the same would be achieved by doing this...
  100.  
  101.         DebugStr('You are about to do blah.');
  102.  
  103. I would recommend that assembly language users use a macro to make the
  104. toolcall and call it _DebugStr.  MPW IIGS Pascal users could use the
  105. following to define the debugstr routine:
  106.  
  107.     Procedure DebugStr(theString:str255);
  108.         INLINE $09FFA2, $E1000022;
  109.  
  110. This call will also work when being called via the glue vector. 
  111. NOTE: Since this call is only available when the debugger is loaded you
  112. will ALWAYS want to be sure to remove ALL calls to the debugger before
  113. releasing your program (or even using it on machines that do not have a
  114. debugger installed).
  115.  
  116.  
  117. SetMileStone:
  118. SetMileStone operates exactly the same way as debugstr except that the
  119. debugger is not actually entered. This will allow tracking of random
  120. crashes by allowing you to call the SetMileStone routine with milestones
  121. that have been met. Any time the debugger is entered via a BRK instruction
  122. or thru the keyboard, the last string passed via the SetMileStone call will
  123. be displayed. The toolcall number for SetMileStone is $0AFF, the  MPW IIGS
  124. Pascal interface might look like this:
  125.  
  126.     Procedure SetMileStone (theString:str255);
  127.         INLINE $0AFFA2, $E1000022;
  128.  
  129.  
  130. DebugVersion, DebugStatus:
  131. These calls are added so that an application can identify the version of the
  132. debugger that is loaded and thus know what calls can be made to the debug
  133. tool. Currently, these calls are identical and return the same result. The
  134. DebugStatus call returns non-zero for true (as opposed to $FFFF which most
  135. people might want...) other than that these calls act the same as any other
  136. toolbox status or version call, each call requires a word space on the stack
  137. for the result which is on the top of the stack when the call completes. If
  138. a debugger is loaded that does not support this feature you will get a
  139. standard tool locator error. For version 1.5b8 the version number returned
  140. is $158F .As you might expect, this number will change as the debugger
  141. version changes and it will always go up, never down.
  142.  
  143.  
  144. Glue Snypher:
  145. Glue snypher is a routine that can recognize high level language tool calls
  146. that are made with the standard glue entry, when a call to glue is detected
  147. while disassembling an instruction the call to glue will be replaced with
  148. *_TooName in a manner similar to how real tool calls now work. Glue snypher
  149. is also used by the memory protect feature, if a glue call is detected
  150. while the standard toolbox memory protect range is on, the glue call will
  151. be treated as if it were a JSL >$e10000.  All glue entries MUST be a JSL
  152. to one of 3 standard types of glue that are shown below:
  153.  
  154.  
  155. ToolGlueType1   LDX #$ToolNum
  156.     JSL >$E10004
  157.     ...
  158.     RTL
  159.  
  160. ToolGlueType2   LDX #$ToolNum
  161.     JML CommonCall
  162.     ...
  163. CommonCall  JSL >$E10004
  164.     ...
  165.     RTL
  166.  
  167. ToolGlueType3   LDX #$ToolNum
  168.     JMP CommonCall
  169.  
  170. If any other types of glue calls are used, they will not be properly detected.
  171.  
  172.  
  173. Glue Breaks:
  174. In addition to glue snypher further support was added for high level
  175. languages by extending the tool break support to the glue vector ($E10004).
  176. Since error conditions are treated differently with glue (The second RTL
  177. ain't mine no more...) it seems unreasonable to also support error breaks
  178. via the glue vector. 
  179.  
  180.  
  181. OSBreaks:
  182. OSBreaks work very much the same way that tool breaks work with three
  183. exceptions. First, instead of breaking on a tool call they will break on
  184. a call to the OS. Next, you can NOT specify an OS break by name, only by
  185. number. Lastly, they are not supported in trace mode, only in real time
  186. mode.  To use OSBreaks you simply type setOSBrk #xxxx where xxxx is the 
  187. number of the OS routine that you want to break on. This number is matched
  188. exactly when an OS call is made, so if you do not know if the target call
  189. is class 0 or class 1 you must set the break for both calls. OSBreaks are
  190. supported via both vectors, inline and stackbased. The following is a
  191. list of commands that operate on OS breaks and what they do.
  192.  
  193. SetOSBrk - adds a number to the OS break list
  194. ClrOSBrk - Removes a given number from the OS break list
  195. ClrAllOSBrk - Removes all numbers from the OS break list
  196. OSBrkIn - enables real time scanning for OS breaks
  197. OSBrkOut - disables real time scanning of OS breaks
  198. ShowBrks - lists all tool and OS breaks currently set.
  199.  
  200.  
  201. DA Debugging support:
  202. In the past it has always been difficult to debug certain new desk
  203. accessories because they accept keystrokes, and keep the debugger from
  204. receiving them. I have added a patching mechanism to the system event
  205. call that is installed when the debugger is installed that fixes this
  206. problem. The way this feature now works is that if the caps lock key is
  207. down no keyboard events get passed to system event (and then to any open
  208. DA's) and the debugger will always get them. A side effect of this is that
  209. when the debugger screen is not active applications will get the same
  210. keystroke events if the CAPS LOCK key is down. As a gentle reminder of
  211. this feature, when installed, it will make your GS speaker click whenever
  212. a key is processed by getNextEvent.  The debugger used to click on every
  213. keystroke, regardless of the state of the CAPS LOCK key.  Dave complained
  214. enough that the debugger was changed to only click when keys are pressed
  215. if the CAPS LOCK key is down.
  216.  
  217.  
  218. New Template types:
  219.  
  220. We have added support for a few more data types in templates, these are
  221. mainly for use with GS/OS strings, but can also be used for any word
  222. length string. they are:
  223.  
  224.     InputStr:   This type will read the next word of data and treat it as
  225.                 a length word for string data that follows. The entire
  226.                 contents of the string will be displayed.
  227.  
  228.     OutputStr:  Similar to InputStr except that the first word is a buffer
  229.                 length and the second word is the string length. After the
  230.                 string is displayed the debugger will skip to the end of
  231.                 the buffer to find the next byte of data to process.
  232.  
  233.  
  234. RealTime Conditional Breakpoints:
  235.  
  236. The debugger now supports conditional real time breakpoints. In the past
  237. when a breakpoint was entered in the breakpoint list and you used the IN
  238. feature to make them work real time, the trigger count that you entered
  239. was ignored. Now, If you the trigger count is supported the same way it is
  240. supported in trace mode, that is, if you insert a real time breakpoint
  241. with a count higher than 1 it will break on the Nth execution of the
  242. opcode at that location. NOTE: Currently the following opcodes are not
  243. supported as real time conditional breakpoints: JSL(mem), JSR(mem),
  244. JSR(mem,x), JMP(mem), JMP(mem,x), RTI.
  245.  
  246. In addition to supporting a count value for real time break points, the
  247. debugger now also allows a simple conditional statement to be used instead.
  248. The debugger allows only one conditional statement at a time, but as many
  249. of the breakpoints can use it as you want. To enable the conditional
  250. statement (henceforth called IF) simply type an "i" when entering a
  251. breakpoints trigger value instead of a hex digit. To set the current IF
  252. use the command SetIF. the syntax of the SetIF command is as follows:
  253.  
  254.     SETIF {width} {Spec1}{Operator}{Spec2}
  255.  
  256. Legal {width} values
  257.      W  for word 
  258.      B  for byte
  259.  
  260. Legal {Operator} values
  261.     =   for is equal to
  262.     #   for is NOT equal to
  263.     <   for is less than
  264.     >   for is Greater than or equal to
  265.  
  266. Legal {Spec1} and {Spec2} values are
  267.     A,X,Y,S,D,P,B   for the corresponding register
  268.     $BBXXXX     as the address of a value in memory
  269.     #$XXXX      as a hexidecimal constant ({SPEC2} only)
  270.  
  271. Some examples of IFs
  272.  
  273.     SETIF W A<#$0101        (Break if the word in <A> is less than #$0101)
  274.     SETIF B $021234=$034321 (Break if the bytes at $02/1234 and $03/4321
  275.                              are the same.)
  276.  
  277. NOTE: Currently only long addresses are supported.
  278.